home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Driver.java < prev    next >
Text File  |  1998-09-22  |  5KB  |  130 lines
  1. /*
  2.  * @(#)Driver.java    1.6 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * <P>The Java SQL framework allows for multiple database drivers.
  19.  *
  20.  * <P>Each driver should supply a class that implements
  21.  * the Driver interface.
  22.  *
  23.  * <P>The DriverManager will try to load as many drivers as it can
  24.  * find and then for any given connection request, it will ask each
  25.  * driver in turn to try to connect to the target URL.
  26.  *
  27.  * <P>It is strongly recommended that each Driver class should be
  28.  * small and standalone so that the Driver class can be loaded and
  29.  * queried without bringing in vast quantities of supporting code.
  30.  *
  31.  * <P>When a Driver class is loaded, it should create an instance of
  32.  * itself and register it with the DriverManager. This means that a
  33.  * user can load and register a driver by doing
  34.  * Class.forName("foo.bah.Driver").
  35.  *
  36.  * @see DriverManager
  37.  * @see Connection 
  38.  */
  39. public interface Driver {
  40.  
  41.     /**
  42.      * Try to make a database connection to the given URL.
  43.      * The driver should return "null" if it realizes it is the wrong kind
  44.      * of driver to connect to the given URL.  This will be common, as when
  45.      * the JDBC driver manager is asked to connect to a given URL it passes
  46.      * the URL to each loaded driver in turn.
  47.      *
  48.      * <P>The driver should raise a SQLException if it is the right 
  49.      * driver to connect to the given URL, but has trouble connecting to
  50.      * the database.
  51.      *
  52.      * <P>The java.util.Properties argument can be used to passed arbitrary
  53.      * string tag/value pairs as connection arguments.
  54.      * Normally at least "user" and "password" properties should be
  55.      * included in the Properties.
  56.      *
  57.      * @param url The URL of the database to connect to
  58.      * @param info a list of arbitrary string tag/value pairs as
  59.      * connection arguments; normally at least a "user" and
  60.      * "password" property should be included
  61.      * @return a Connection to the URL
  62.      * @exception SQLException if a database-access error occurs.
  63.      */
  64.     Connection connect(String url, java.util.Properties info)
  65.         throws SQLException;
  66.  
  67.     /**
  68.      * Returns true if the driver thinks that it can open a connection
  69.      * to the given URL.  Typically drivers will return true if they
  70.      * understand the subprotocol specified in the URL and false if
  71.      * they don't.
  72.      *
  73.      * @param url The URL of the database.
  74.      * @return True if this driver can connect to the given URL.  
  75.      * @exception SQLException if a database-access error occurs.
  76.      */
  77.     boolean acceptsURL(String url) throws SQLException;
  78.  
  79.  
  80.     /**
  81.      * <p>The getPropertyInfo method is intended to allow a generic GUI tool to 
  82.      * discover what properties it should prompt a human for in order to get 
  83.      * enough information to connect to a database.  Note that depending on
  84.      * the values the human has supplied so far, additional values may become
  85.      * necessary, so it may be necessary to iterate though several calls
  86.      * to getPropertyInfo.
  87.      *
  88.      * @param url The URL of the database to connect to.
  89.      * @param info A proposed list of tag/value pairs that will be sent on
  90.      *          connect open.
  91.      * @return An array of DriverPropertyInfo objects describing possible
  92.      *          properties.  This array may be an empty array if no properties
  93.      *          are required.
  94.      * @exception SQLException if a database-access error occurs.
  95.      */
  96.     DriverPropertyInfo[] getPropertyInfo(String url, java.util.Properties info)
  97.              throws SQLException;
  98.  
  99.  
  100.     /**
  101.      * Get the driver's major version number. Initially this should be 1.
  102.      */
  103.     int getMajorVersion();
  104.  
  105.     /**
  106.      * Get the driver's minor version number. Initially this should be 0.
  107.      */
  108.     int getMinorVersion();
  109.  
  110.  
  111.     /**
  112.      * Report whether the Driver is a genuine JDBC COMPLIANT (tm) driver.
  113.      * A driver may only report "true" here if it passes the JDBC compliance
  114.      * tests, otherwise it is required to return false.
  115.      *
  116.      * JDBC compliance requires full support for the JDBC API and full support
  117.      * for SQL 92 Entry Level.  It is expected that JDBC compliant drivers will
  118.      * be available for all the major commercial databases.
  119.      *
  120.      * This method is not intended to encourage the development of non-JDBC
  121.      * compliant drivers, but is a recognition of the fact that some vendors
  122.      * are interested in using the JDBC API and framework for lightweight
  123.      * databases that do not support full database functionality, or for
  124.      * special databases such as document information retrieval where a SQL
  125.      * implementation may not be feasible.
  126.      */
  127.     boolean jdbcCompliant();
  128. } 
  129.  
  130.